使用网格列表框 (Grid List Box) 节点

网格列表框 (Grid List Box) 节点可用于创建以网格形式排列的项的可滚动列表。

通过完成教程学习如何使用网格列表框 (Grid List Box)节点。请参阅教程：使用网格列表框 (Grid List Box) 创建联系人列表。

在您为网格列表框 (Grid List Box) 节点添加项时，网格列表框 (Grid List Box) 节点会将这些项放在自己的第一行或第一列中：

要选择 网格列表框 (Grid List Box) 节点中的项，请点击或轻敲该项。

网格列表框 (Grid List Box) 节点根据您在 布局方向 (Layout Direction) 属性中设置的值排列自己的项：

网格列表框 (Grid List Box) 节点有焦点时，使用：

注

所有列表框节点（网格列表框 (Grid List Box) 节点和3D 轨迹列表框 (Trajectory List Box 3D) 节点）中的项不是其子节点，即使在 Kanzi Studio 中将项添加到列表框时看似是子节点。由于列表框项不是列表框的子节点，您不能使用路径或别名从列表框的外部引用这些项。要从列表框项引用到列表框外的对象，应使用绑定和别名。请参阅绑定到 网格列表框 (Grid List Box) 节点以外的属性以及从 网格列表框 (Grid List Box) 节点导航到 页面 (Page) 节点。

对于 网格列表框 (Grid List Box) 节点，您可以：

创建 网格列表框 (Grid List Box) 节点

要创建 网格列表框 (Grid List Box) 节点：

  1. 在工程 (Project) 中按下 Alt 并右键点击要在其中创建网格列表框 (Grid List Box) 节点的那个节点，然后选择 3D 网格列表框 (Grid List Box 3D) 或 2D 网格列表框 (Grid List Box 2D)。
    请注意，只能在 3D 节点内创建 3D 节点，只能在 2D 节点内创建 2D 节点。
  2. 在工程 (Project) 中，将项添加到网格列表框 (Grid List Box) 节点。
    使用数据源为 列表框 (List Box) 节点添加项。请参阅使用数据源。
    例如，要创建联系人列表，请添加多个代表列表中的联系人的节点。请参阅使用列表框项容器 (List Box Item Container) 预设件。
    当添加项时，网格列表框 (Grid List Box) 节点会在网格中将它们从 网格列表框 (Grid List Box) 节点的左上角至左下角排列。请参阅设置 网格列表框 (Grid List Box) 节点如何排列自己的项。
    要在 网格列表框 (Grid List Box) 节点中浏览项，请在预览 (Preview) 中点击项并将其拖到 网格列表框 (Grid List Box) 节点中。
  3. （可选） 如果看不到您为 网格列表框 (Grid List Box) 节点添加的内容或者内容不完全适合，请添加并设置 单元格高度 (Cell Height) 和 单元格宽度 (Cell Width) 属性。
    您需要设置为列表框内的每个元素保留的区域。如果项不适合单元格，单元格的大小会裁剪这些项。
  4. 在 工程 (Project) 中，选择 网格列表框 (Grid List Box) 节点，然后在 属性 (Properties) 中设置 布局高度 (Layout Height) 和 布局宽度 (Layout Width) 属性。
    您需要设置 网格列表框 (Grid List Box) 节点中的项要在哪个区域中可见。如果 网格列表框 (Grid List Box) 节点中的所有项并非都适合区域，Kanzi 会剪辑不适合的那些项。用户可以滚动 网格列表框 (Grid List Box) 节点以访问所有的项。
  5. （可选） 在 预览 (Preview) 中点击 以进入 分析 (Analyze) 模式，然后右键点击 并选择 调试对象 (Debug objects)。
    这样即可可视化网格列表框 (Grid List Box) 节点的边框和网格列表框 (Grid List Box) 节点中的项。

设置 网格列表框 (Grid List Box) 节点如何排列自己的项

您可以设置 网格列表框 (Grid List Box) 节点，以使其沿 x 或 y 轴排列自己的项。

要设置 网格列表框 (Grid List Box) 如何排列自己的项：

  1. 创建网格列表框 (Grid List Box) 节点并向其添加项。请参阅创建 网格列表框 (Grid List Box) 节点。
  2. 在属性 (Properties) 中将 布局方向 (Layout Direction) 属性设置为：

将选定的项放到网格列表框 (Grid List Box) 中心

您可以设置 网格列表框 (Grid List Box) 节点，以使其在用户点击或轻敲项时将项置于列表框区域的中心。

要在用户选择 网格列表框 (Grid List Box) 节点中的项时将它们设置在中心：

  1. 创建网格列表框 (Grid List Box) 节点并向其添加项。请参阅创建 网格列表框 (Grid List Box) 节点。
  2. 在 属性 (Properties) 中，添加 选择行为 (Selection Behavior) 属性并将其设置为 移动到中心 (Bring Center)。
    您需要设置 网格列表框 (Grid List Box) 节点，以使其在用户选择某个项时将项滚动到节点的中心。网格列表框 (Grid List Box) 节点根据您在 布局方向 (Layout Direction) 属性中设置的值将自己的项置于中心。请参阅设置 网格列表框 (Grid List Box) 节点如何排列自己的项。
  3. 在 属性 (Properties) 中，添加：

    使用 项区域开始 (Item Area Begin) 和 项区域结束 (Item Area End) 属性：

嵌套网格列表框 (Grid List Box)节点

您可以嵌套网格列表框 (Grid List Box) 节点，以在网格列表框 (Grid List Box) 节点中创建网格列表框 (Grid List Box) 节点，其中每个都可以独立滚动。例如，您可以创建：

在网格列表框 (Grid List Box) 节点中使用布局方向 (Layout Direction) 属性设置网格列表框 (Grid List Box) 节点如何排列其项目，并设置用户可以滚动的轴。将布局方向 (Layout Direction) 设为：

要嵌套网格列表框 (Grid List Box) 节点：

  1. 创建网格列表框 (Grid List Box) 节点。请参阅创建 网格列表框 (Grid List Box) 节点。
    默认情况下，布局方向 (Layout Direction) 属性的值为右对齐 (Right)，您可以在 y 轴上滚动列表项。要沿 x 轴滚动列表项，将布局方向 (Layout Direction) 设置为下对齐 (Down)。
  2. 为上一步中创建的网格列表框 (Grid List Box) 节点的各列表项创建结构。
    例如，如果要创建多个包含相册的嵌套网格列表框 (Grid List Box) 节点，在预设件 (Prefabs) 中创建 2D 堆栈布局 (Stack Layout 2D) 节点，并在其中创建 2D 文本块 (Text Block 2D) 节点。
    您使用2D 堆栈布局 (Stack Layout 2D) 节点定位每个嵌套网格列表框 (Grid List Box) 和相册类别标题，以及 2D 文本块 (Text Block 2D) 节点以显示类别标题。请参阅使用堆栈布局 (Stack Layout) 节点。
  3. 创建要在第一步创建的网格列表框 (Grid List Box) 中嵌套的网格列表框 (Grid List Box) 节点，并将其设置为在与其父网格列表框 (Grid List Box) 节点不同的轴上滚动。如果将父网格列表框 (Grid List Box) 节点的布局方向 (Layout Direction) 属性设置为右对齐 (Right)，将嵌套网格列表框 (Grid List Box) 节点的属性设置为下对齐 (Down)，以在 x 轴上滚动网格列表框 (Grid List Box)。
    例如，如果在上一步中创建了 2D 堆栈布局 (Stack Layout 2D) 预设件，在 2D 堆栈布局 (Stack Layout 2D) 中创建网格列表框 (Grid List Box) 节点，将该预设件的多个实例拖动至网格列表框 (Grid List Box) 节点的工程 (Project)。
  4. 添加项到各嵌套网格列表框 (Grid List Box) 节点。
    例如，要创建包含水平滚动相册网格列表框 (Grid List Box) 的垂直滚动网格列表框 (Grid List Box)，在预设件 (Prefabs) 中创建表示各相册的图像 (Image) 节点，并将多个预设件实例拖动到各嵌套网格列表框 (Grid List Box)。
    您可以使用数据源添加项到网格列表框 (Grid List Box)。请参阅使用数据源。

绑定到 网格列表框 (Grid List Box) 节点以外的属性

要将列表框项的属性绑定到列表框外的节点的属性，应使用别名。

例如，如果您有一个3D 网格列表框 (Grid List Box 3D) 节点或具有3D 文本块 (Text Block 3D) 节点项的3D 轨迹列表框 (Trajectory List Box 3D) 节点，并要将3D 文本块 (Text Block 3D) 节点的文本 (Text) 属性值设置为不在列表框中的3D 空节点 (Empty Node 3D) 节点属性值：

  1. 在工程 (Project) 中，按下 Alt 并右键点击包含要绑定到其中的属性的节点并选择别名 (Alias)。请参阅使用别名。
    例如，为3D 空节点 (Empty Node 3D) 节点创建一个别名。
  2. 在字典 (Dictionaries) 中确保您创建的别名在列表框节点可以访问的资源字典中。
    例如，将所有别名放到屏幕 (Screen) 节点的资源字典中，或者在列表框节点中创建资源字典，并将别名放在该资源字典中。请参阅使用资源字典。
  3. 创建绑定：
    1. 在工程 (Project) 中，选择列表框节点内的节点，您要从其绑定至该列表框节点外的一个节点。
    2. 在属性 (Properties) 中添加绑定 (Bindings) 属性并使用别名创建绑定，以绑定到列表框节点外的节点中的属性。
      例如，在3D 文本块 (Text Block 3D) 节点中，使用您在第一步中创建的别名创建对3D 空节点 (Empty Node 3D) 节点的绑定。请参阅绑定表达式参考。
      例如，使用以下绑定表达式： 
      {#Empty Node 3D/TextBlockConcept.Text}

      3D 文本块 (Text Block 3D) 节点中的文本 (Text) 属性从3D 空节点 (Empty Node 3D) 节点获取文本 (Text) 属性的值。
    3. 点击保存 (Save)。

从 网格列表框 (Grid List Box) 节点导航到 页面 (Page) 节点

要从列表框节点中的节点导航到页面 (Page) 节点，应使用别名。例如，如果您使用网格列表框 (Grid List Box) 或3D 轨迹列表框 (Trajectory List Box 3D) 节点创建地址簿，并想要显示页面 (Page) 节点中的地址簿条目的内容。

要从列表框节点导航到页面 (Page) 节点：

  1. 在工程 (Project) 中按下 Alt 并右键点击您要导航至其的每个页面 (Page) 节点并选择别名 (Alias)。
    Kanzi Studio 即会创建指向创建它时所在的节点的别名，并将别名放到最近的资源字典中。
  2. 在字典 (Dictionaries) 中确保您创建的别名在列表框节点可以访问的资源字典中。
    例如，将所有别名放到屏幕 (Screen) 节点的资源字典中，或者在列表框节点中创建资源字典，并将别名放在该资源字典中。请参阅使用资源字典。
  3. 添加并设置导航至页面 (Navigate to Page) 动作：
    1. 在工程 (Project) 的列表框节点中选择该节点，其中包含您要用于导航到第一步中为其创建别名的一个页面 (Page) 节点的触发器。
    2. 在要用于导航到页面 (Page) 节点的触发器的节点组件 (Node Components) > 触发器 (Triggers) 部分添加导航至页面 (Navigate to Page) 动作。
    3. 在导航至页面 (Navigate to Page) 设置窗口中，将项 (Item) 属性设置为要导航到的页面 (Page) 节点的别名，并点击保存 (Save)。
      所有别名都以 ＃ 号开头。

在预览 (Preview) 中，点击包含导航至页面 (Navigate to Page) 动作的节点，即会激活动作中选定的页面 (Page) 节点。

在用户与 网格列表框 (Grid List Box) 节点交互时响应

使用 列表框 (List Box) 触发器在用户与 网格列表框 (Grid List Box) 节点交互时响应。例如，您可以设置用户滚动节点时的网格列表框 (Grid List Box) 节点外观。

您可通过网格列表框 (Grid List Box) 节点使用这些列表框 (List Box) 触发器：

要使用带 网格列表框 (Grid List Box) 节点的列表框 (List Box) 触发器：

  1. 创建网格列表框 (Grid List Box) 节点并向其添加项。请参阅创建 网格列表框 (Grid List Box) 节点。
    例如，创建一个2D 网格列表框 (Grid List Box 2D) 节点。
  2. 定义您想通过列表框 (List Box) 触发器设置的行为。
    例如，创建状态机，您可以定义状态以设置 2D 网格列表框 (Grid List Box 2D) 节点在列表框: 滚动已开始 (List Box: Scroll Started) 和列表框: 滚动已完成 (List Box: Scroll Finished) 触发器被触发时的外观。请参阅创建状态机。
  3. 添加和配置列表框 (List Box) 触发器：
    1. 在工程 (Project) 中，选择要为其添加触发器的列表框 (List Box) 节点，并在节点组件 (Node Components) > 触发器 (Triggers) 部分添加其中一个列表框 (List Box) 触发器。
      例如，在工程 (Project) 中选择您在此程序开始时创建的网格列表框 (Grid List Box) 节点，并在节点组件 (Node Components) 中添加 列表框: 滚动已开始 (List Box: Scroll Started) 触发器。
    2. 在您上一步创建的触发器中，选择添加 (Add) 下拉菜单中的动作，并配置该动作。
      例如，选择转到状态 (Go to State) 动作并在动作设置中设置：
      • 项 (Item) 为您在此步骤开始时创建的网格列表框 (Grid List Box) 节点
      • 状态 (State) 为设置 网格列表框 (Grid List Box) 节点在 列表框: 滚动已开始 (List Box: Scroll Started) 触发器被触发时的外观的状态。
  4. 重复上一步，以添加并配置更多列表框 (List Box) 触发器。
    例如，添加列表框: 滚动已完成 (List Box: Scroll Finished) 触发器。在触发器的转到状态 (Go to State) 动作中，将状态 (State) 设置为设置当触发器被处罚时节点外观的状态。

在预览 (Preview) 中，当滚动您创建的 网格列表框 (Grid List Box) 节点时，您添加的触发器被触发。

设置 2D 网格列表框 (Grid List Box 2D) 节点的外观

要设置 2D 节点的外观：

在 API 中使用 3D 网格列表框 (Grid List Box 3D) 节点

要创建 3D 网格列表框：

//创建一个名为 MyListBox 的 3D 网格列表框。
GridListBox3DSharedPtr gridListBox = GridListBox3D::create(domain, "MyListBox");

要配置网格区域：

//使所有网格单元格成为 1x1x1 立方体。
gridListBox->setCellWidth(1.0f);
gridListBox->setCellHeight(1.0f);
gridListBox->setDepth(1.0f);
//使网格包含 3 个逐列填充的行。
gridListBox->setHeight(3.0f);
gridListBox->setDirection(GridListBoxConcept::GridDirectionDown);
//使网格包含 10 列。拖到这些列之外的项将不可见。
gridListBox->setWidth(10.0f);
//将列表滚动到开头或末尾并更改停放位置，以使这些项不再位于网格边缘。
gridListBox->setItemAreaBegin(0.2f);
gridListBox->setItemAreaEnd(0.8f);

要将项添加到列表框：

//创建立方体网格并将它们添加为列表框中的项。
//网格上的项将按您将其添加到列表中时所使的顺序显示。
Model3DSharedPtr item1 = Model3D::createCube(domain, "item1", 1.0f, ThemeRed);
Model3DSharedPtr item2 = Model3D::createCube(domain, "item2", 1.0f, ThemeGreen);
Model3DSharedPtr item3 = Model3D::createCube(domain, "item3", 1.0f, ThemeBlue);
Model3DSharedPtr item4 = Model3D::createCube(domain, "item4", 1.0f, ThemeOrange);
Model3DSharedPtr item5 = Model3D::createCube(domain, "item5", 1.0f, ThemeYellow);
gridListBox->addItem(item1);
gridListBox->addItem(item2);
gridListBox->addItem(item3);
gridListBox->addItem(item4);
gridListBox->addItem(item5);

有关详细信息，请参阅 API reference中的 GridListBox3D 类。

在 API 中使用 2D 网格列表框 (Grid List Box 2D) 节点

要创建 2D 网格列表框：

//创建一个名为 MyListBox 的 2D 网格列表框。
GridListBox2DSharedPtr gridListBox = GridListBox2D::create(domain, "MyListBox");

要配置网格区域：

//使所有网格单元格成为 100x100 正方形。
gridListBox->setCellWidth(100.0f);
gridListBox->setCellHeight(100.0f);
//使网格包含 3 个逐列填充的行。
gridListBox->setHeight(300.0f);
gridListBox->setDirection(GridListBoxConcept::GridDirectionDown);
//使网格包含 10 列。拖到这些列之外的项将不可见。
gridListBox->setWidth(1000.0f);
//将列表滚动到开头或末尾并更改停放位置，以使这些项不再位于网格边缘。
gridListBox->setItemAreaBegin(0.2f);
gridListBox->setItemAreaEnd(0.8f);

要将项添加到列表框：

//创建图像并将它们添加为列表框中的项。
//网格上的项将按您将其添加到列表中时所用的顺序显示。
for (int i = 0; i < 5; ++i)
{
    Image2DSharedPtr item = Image2D::create(domain, "item" + to_string(i));
    item->setImage(item->acquireResource<Texture>(ResourceID("DefaultTexture")));
    //使图像缩小至单元格大小。
    item->setHorizontalAlignment(Node::HorizontalAlignmentStretch);
    item->setVerticalAlignment(Node::VerticalAlignmentStretch);
    gridListBox->addItem(item);
}

有关详细信息，请参阅 API reference中的 GridListBox2D 类。

网格列表框 (Grid List Box) 属性类型和消息

要查看 网格列表框 (Grid List Box) 节点可用属性类型和消息的列表，请参阅 Grid list box 2D和 Grid list box 3D。

另请参阅

教程：使用网格列表框 (Grid List Box) 创建联系人列表

使用 3D 轨迹列表框 (Trajectory List Box 3D) 节点

使用网格布局 (Grid Layout) 节点

使用列表框项容器 (List Box Item Container) 预设件

使用 Kanzi Studio 为节点启用点击手势

打开导航